Skip to content

Kit v1.4.0: shared naming conventions, PPTX extractor, package and ZIP prunes - #3

Merged
ThisIsTJ merged 5 commits into
mainfrom
feat/shared-naming-conventions
Aug 24, 2026
Merged

ThisIsTJ merged 5 commits into
mainfrom
feat/shared-naming-conventions

Conversation

@ThisIsTJ

Copy link
Copy Markdown
Collaborator

Releases the kit as v1.4.0. package.json already says 1.4.0; no tag existed, so no repo could receive any of this.

What's here

Shared naming conventions in the agents base (16329c9) — the conventions now live in the kit's agents/base.md, so agents build propagates them to all five content repos instead of each repo restating them.

extract-pptx moved into the kit (ebf42c3) — two repos had drifting copies of extract-pptx-assets.py. The deck-specific slide ranges and role keywords became a --slide-map JSON, so the code is shared and the deck knowledge stays with the workshop. doctor now flags a leftover scripts/extract-pptx-assets.py. Includes the placeholder-picture fix, regression-tested against a fixture deck whose image sits in a content placeholder.

Prune old packages after codedapp pack (3efdaf9) — keeps 3 per package name. .uipath/ grew without bound before. Per package name, not globally: one repo packs a different app name per training target, and a global "keep newest N" would destroy an older target's only package.

Prune orphaned zips in static/downloads/ (a5a6d2f) — see below.

Versioning docs correction (4dc2ebb) — how consumers actually get a release.

Why the ZIP prune matters more than it looks

A deleted downloads/<name>/ folder left its ZIP behind forever, and the failure mode is genuinely invisible:

  • static/downloads/ is gitignored, so a stale ZIP is in no commit, no diff, no PR, and CI never sees it
  • but codedapp pack packs the local build/ directory, and Docusaurus copies all of static/ into it
  • so a file orphaned on one laptop kept shipping to the deployed tenant

coding-agents-workshop served a July exercise-1.zip and exercise-2.zip this way for a month. Both are now deleted and the prune stops it recurring in any repo.

Behaviour: only .zip files are considered, so anything else a repo keeps in static/downloads/ is untouched. It prunes when downloads/ is emptied — that is exactly the CA shape — but does nothing when downloads/ is absent entirely, since the kit is not managing that directory then.

Testing

New kit-ci.yml step, mutation-tested against three mutations: dropping the prune call, ignoring the keep-set, and pruning non-zip files.

One subtlety worth recording: the test must seed the current ZIP as well as the orphan. On a fresh tree, a prune that ignores its keep-set is unobservable — there is no current ZIP for it to wrongly delete, and generation immediately recreates anything it removed. The first version of this test passed against that mutation. It now asserts on the log line instead of file existence.

All five content repos were built against this branch and pass with zero anchor warnings.

After merge

Tag v1.4.0, force-move the v1 major tag, then npx workshop-kit repin v1.4.0 in each of the five content repos. Nothing breaks without the repin — the repos are on v1.3.0 and these are authoring/deploy-time changes — but the comms-mining README and AGENTS.md already name an extract-pptx command their pinned kit lacks, and .uipath/ keeps growing until it lands.

🤖 Generated with Claude Code

ThisIsTJ and others added 5 commits August 21, 2026 14:18
Four kinds of drift had accumulated across the five workshop repos, each one
locally reasonable and collectively confusing for a participant who attends more
than one workshop. Record the agreed convention in one place so a content repo
can point at it instead of restating or overriding it.

New "Shared Naming Conventions" section:
- The prerequisites page is titled `Prerequisites`, or `Prerequisites - <Step>`
  where a workshop splits it. Was a three-way split between `Pre-reqs -`,
  `Pre-req -` and `Prerequisites`.
- Every exercise page closes with one `## Success check` list. Was a mix of
  `Success Criteria` plus a near-duplicate `Verification Checks`, `Success check`
  and `Recap`. An up-front `Requirements` or `Objectives` section is unaffected.
- Participant placeholders use angle brackets: `<your-name>`, `<your-initials>`.
  Was `[participant name]`, `<your-name>` and `{{your-initials}}`.
- `{{ }}` is reserved for `{{WORKSHOP_*}}` tokens, so nothing a participant
  replaces by hand may use that shape. `{{your-initials}}` looked exactly like a
  build-time token and silently was not one.
- `sidebar_position` runs contiguously from 1, and front matter `title` must
  match the page `# H1`.

Also, under Workshop Configuration Variables: no delivery-specific literal
belongs in `docs/`. A tenant URL, org, join link, Studio Web template name,
cohort, city or date goes in `config/workshop-targets.json` and renders through
the WorkshopEnv components. Two repos had a city and a date baked into a template
name participants must search for, and one had a hardcoded tenant URL five lines
below the same value rendered from a variable.

And under Downloads And Assets:
- Serve participant files through `WorkshopDownloadLink`, never an external file
  host. The IXP workshop linked two Google Drive files that could not be
  versioned with the content.
- Name a download for what is inside it, not just the exercise number.

This needs a release and a repin before the fenced AGENTS.md regions in the
content repos pick it up.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two content repos each carried a copy of `scripts/extract-pptx-assets.py`,
the tool that pulls screenshots, ordered text blocks and callout geometry out
of a facilitator deck. The copies had diverged, and the older one was the
broken one — exactly the drift the kit exists to stop.

The IXP copy filtered on `shape.shape_type == MSO_SHAPE_TYPE.PICTURE`. An image
dropped into a PowerPoint content placeholder is a `PlaceholderPicture`, whose
shape_type is PLACEHOLDER, so it was skipped. On the Communications Mining deck
that silently lost 18 of 33 screenshots, with no error and no non-zero exit. The
CM copy had the three-line fix and a `callout_markers` pass the IXP copy lacked.

Rather than port the fix to a second copy, the fixed version moves here and both
per-repo copies go away.

Generalised for sharing:
- `page_for_slide` and `likely_role` were hardcoded to one deck's slide numbers
  and keywords. They are now an optional `--slide-map` JSON, so the code is
  shared while the deck-specific knowledge stays in the workshop that owns the
  deck. `schemas/pptx-slide-map.schema.json` documents the shape; slides are
  given as integers or inclusive `"N-M"` ranges, and role rules match on slide
  number, on case-insensitive text, or both, first rule winning.
- Without a map every slide lands in one folder, which is the right first pass
  over an unfamiliar deck — you cannot write the slide-to-page table until you
  have seen what came out. The run reports how many slides landed there, because
  a map written against a stale deck revision otherwise looks like a success.

`workshop-kit extract-pptx` wraps it. python-pptx and Pillow are deliberately
not project dependencies — this is a one-off authoring step, not part of any
build — so the wrapper probes for an interpreter (PYTHON, python3, python) and
the two modules, and prints the pip line instead of a traceback.

`doctor` now reports a leftover `scripts/extract-pptx-assets.py` alongside the
other files a migrated repo should no longer have.

Verified against a fixture deck built for the purpose: one pasted picture, one
dropped into a content placeholder, and a numbered oval overlapping a third. All
three extracted, including the placeholder one; pages routed by both range and
keyword rules; the callout marker computed to 25.0%/25.0%, matching the geometry
by hand. The missing-dependency path was checked too. CI gained an `ast.parse`
check on the extractor, since no build step exercises it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`uip codedapp pack` writes a fresh timestamped `.uipath/<name>.<version>.nupkg`
on every run and never removes one. Nothing else cleans them up either, so the
directory grows without bound: coding-agents-workshop reached 147 MB across 21
files in two months. They are gitignored, so this shows up as disk use rather
than as a diff, and nobody notices.

After a successful pack, keep the newest 3 per package name and delete the rest,
reporting what went and how much was freed. `UIPATH_CODEDAPP_KEEP` overrides;
below 1 or non-numeric warns and falls back to 3.

Per NAME, not per directory. That repo packs a different app name per training
target — tc20260721-ca-workshop, ifca20260722-ca-workshop, growth-*, and so on.
A global "keep the newest 3" would have kept three tc20260727-* files and deleted
growth-coding-agents-workshop, the only package of its name. `publish` is a
separate command that runs against the local file, so that breaks pack-now-
publish-later. Grouping by name also guarantees the file the current run just
produced survives, since it is the newest in its own group.

Deliberately conservative about what it will touch:
- The version is anchored as a trailing semver rather than assumed to start at
  the first dot, so a package name containing a dot still splits correctly.
- Anything not matching `<name>.<semver>.nupkg` is left alone, `app.config.json`
  and `metadata.json` included.
- Local packages are build artifacts, not the deliverable; publish has already
  uploaded to Orchestrator.

Tested against a fixture replicating that repo's exact 21 files and mtimes:
21 -> 14 across six name groups, oldest of each group dropped, newest kept,
single-file groups untouched, config files untouched, unparseable names
untouched, KEEP=1 and KEEP=10 honoured, KEEP=0 and KEEP=abc rejected with a
warning, and a missing `.uipath/` returning quietly. CI carries the case that
matters — a name never packed again surviving while another name is pruned.

`prunePackages` is exported and `main()` now runs only on direct execution, so
the delete path can be exercised without spawning the whole deploy script. The
module is always spawned as a script in production, so the guard is inert there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The section said content repos "pin a caret range and rely on Dependabot to
surface kit releases". Both halves are wrong, and the Releasing section directly
above it already said the opposite. The whole workshop-kit approach depends on
this being unambiguous, so a reader hitting the contradiction has no way to tell
which one governs.

Reality, checked against all five content repos: every one pins the exact tag
`github:UiPath-LAB-TEC/workshop-kit#v1.3.0`, resolved through package-lock.json
to a specific commit. There is no caret range anywhere. The caret-plus-registry
model was considered and rejected — the workspace TODO records the decision as
"public repo + git tag, no registry, no auth. Exact pins rather than semver
ranges" — and this paragraph was left over from that draft.

Rewritten around the fact everything else follows from: the version number is a
signal, not a trigger. Dependabot cannot bump a `github:` tag (no registry to
poll, no range to compare), `npm install` cannot either (the lockfile pins the
previous tag's commit), and only `workshop-kit repin <tag>` moves a repo, run
per repo on purpose. Each content repo's dependabot.yml already carries this in
a comment, including that a kit group once sat there doing nothing.

Also states the two consequences that were never written down: a major does not
break every workshop the day it is tagged, only the next repo that repins — a
delivered workshop can sit on an old tag indefinitely, which is the point. And
the mirror image, that a shared fix is not live anywhere until each repo is
repinned, so cross-repo CI proves a change is safe without delivering it.

A new CLI command is added to the minor bullet, since two of them have now
shipped as minors with the rule unstated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A deleted downloads/<name>/ folder left its ZIP behind forever. That is
not merely untidy. static/downloads/ is gitignored, so a stale ZIP is
invisible to CI and to review, but `codedapp pack` packs the local build/
directory and Docusaurus fills that from static/ -- so the orphan kept
shipping to the deployed site. coding-agents-workshop served a July
exercise-1.zip and exercise-2.zip that way until today.

Only .zip files are considered, so anything else a repo keeps in
static/downloads/ survives. The prune runs before the early exit for an
empty downloads/, because an emptied folder is exactly the case where
every remaining ZIP is an orphan. It does nothing when downloads/ is
absent entirely: the kit is not managing that directory then.

The CI test seeds the current ZIP as well as an orphan. Without that, a
prune ignoring its keep-set passes unnoticed -- on a fresh tree there is
no current ZIP for it to wrongly delete, and generation immediately
recreates whatever the prune removed. Mutation-tested against dropping
the prune call, ignoring the keep-set, and pruning non-zip files.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ThisIsTJ
ThisIsTJ merged commit 14ef7ca into main Aug 24, 2026
1 check passed
@ThisIsTJ
ThisIsTJ deleted the feat/shared-naming-conventions branch August 24, 2026 19:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant